Documentation

inbox/Movements Investigation - Shipments vs. Movements.md

Movements Investigation: Shipments vs. Movements

Why this doc exists

We need basket turns to work now using shipment data, but we also need to validate whether the movements table should be the canonical movement ledger and fix shipment-related movements if they are missing.

Current observations

  • spatial.movements records are mostly (or entirely) tagged as Internal.
  • Shipment lifecycle data exists in transport.* (shipments, deliveries, allocations).
  • Analytics built on movements will under-report shipment movement activity if shipment movements are not being created.

Goal

Confirm whether shipment movements are:

  1. Expected but missing due to implementation gaps, or
  2. Intentionally excluded (and movements are only for internal moves).

Questions to answer

  • Where are shipment allocations created/updated (e.g., shipment lifecycle processors)?
  • Is there a code path that is supposed to create movements rows for shipment events?
  • Do we have a mapping between shipment statuses and movement types?
  • Is there a historical reason movements are internal-only?
  • Should movements become the canonical source for turns/dwell/locations, or should shipments/deliveries remain canonical?

Data checks to run (read-only)

  • Compare counts of shipments/deliveries vs. movements by type and time window.
  • Check for any movements tied to shipment ids (if a relation exists).
  • Verify whether movement_type_id “Shipment” has any rows at all.
  • Sample a basket that has multiple deliveries and check if any movements exist for it.

Code paths to inspect

  • Shipment creation and status updates:
    • Acsis.Dynaplex.Engines.Bbu/Services/ShipmentLifecycleProcessor.cs
    • Acsis.Dynaplex.Engines.Bbu/Services/OracleProcessor.cs
  • Return/door processing (internal movement creation):
    • Acsis.Dynaplex.Engines.Bbu/Services/ReturnDoorProcessor.cs
  • Any movement creation utilities or services in spatial/transport components.

Decision points

  • If shipment movements are required:
    • Add movement creation when shipment status transitions occur (e.g., SHIPPED/DELIVERED/RETURNED).
    • Backfill movements for recent shipment history if needed for analytics.
  • If shipment movements are not required:
    • Document that movements are internal-only.
    • Ensure analytics (turns/dwell) use shipments/deliveries instead.

Deliverables

  • Clear recommendation on the canonical source of truth (movements vs shipments).
  • Implementation plan (including tests/data backfill if needed).